package com.kexio.user.mapper;

import java.util.List;

import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.kexio.user.entity.Role;

/**
 * 角色数据访问层
 * 
 * 基于MyBatis Plus的角色数据访问接口，提供：
 * - 基础CRUD操作（继承自BaseMapper）
 * - 角色权限关联查询
 * - 角色用户关联查询
 * - 角色层级关系处理
 * - 多租户数据隔离
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
@Mapper
public interface RoleMapper extends BaseMapper<Role> {
    
    // ==================== 基础查询 ====================
    
    /**
     * 根据角色编码和租户ID查询角色
     * 
     * @param roleCode 角色编码
     * @param tenantId 租户ID
     * @return 角色信息
     */
    Role selectByRoleCodeAndTenant(@Param("roleCode") String roleCode);
    
    /**
     * 查询租户下的所有角色
     * 
     * @param tenantId 租户ID
     * @return 角色列表
     */
    List<Role> selectByTenant();
    
    // ==================== 权限关联查询 ====================
    
    /**
     * 查询角色拥有的权限列表
     * 
     * @param roleId 角色ID
     * @param tenantId 租户ID
     * @return 权限列表
     */
    List<com.kexio.user.entity.Permission> selectRolePermissions(@Param("roleId") String roleId);
    
    /**
     * 查询角色拥有的权限编码列表
     * 
     * @param roleId 角色ID
     * @param tenantId 租户ID
     * @return 权限编码列表
     */
    List<String> selectRolePermissionCodes(@Param("roleId") String roleId);
    
    /**
     * 查询拥有指定权限的角色列表
     * 
     * @param permissionCode 权限编码
     * @param tenantId 租户ID
     * @return 角色列表
     */
    List<Role> selectRolesByPermission(@Param("permissionCode") String permissionCode);
    
    /**
     * 根据角色编码查询该角色拥有的权限编码列表
     */
    List<String> selectRolePermissionCodesByRoleCode(@Param("roleCode") String roleCode);
    
    // ==================== 用户关联查询 ====================
    
    /**
     * 查询用户拥有的角色列表
     * 
     * @param userId 用户ID
     * @param tenantId 租户ID
     * @return 角色列表
     */
    List<Role> selectUserRoles(@Param("userId") String userId);
    
    /**
     * 查询用户拥有的角色编码列表
     */
    List<String> selectUserRoleCodes(@Param("userId") String userId);
    
    /**
     * 查询角色下的用户列表
     * 
     * @param roleId 角色ID
     * @param tenantId 租户ID
     * @return 用户列表
     */
    List<com.kexio.user.entity.User> selectRoleUsers(@Param("roleId") String roleId);
    
    /**
     * 查询拥有指定角色的用户数量
     * 
     * @param roleId 角色ID
     * @param tenantId 租户ID
     * @return 用户数量
     */
    default long countRoleUsers(@Param("roleId") String roleId) {
        // 使用 XML 中的 user-role 统计更合适；这里提供基于角色表的启用角色计数示例
        // 实际用户计数建议在 UserRoleMapper 中提供默认方法
        return 0L;
    }
    
    // ==================== 角色层级查询 ====================
    
    /**
     * 查询角色的直接子角色
     * 
     * @param parentRoleId 父角色ID
     * @param tenantId 租户ID
     * @return 子角色列表
     */
    List<Role> selectChildRoles(@Param("parentRoleId") Long parentRoleId);
    
    /**
     * 查询角色的所有祖先角色（向上查询）
     * 
     * @param roleId 角色ID
     * @param tenantId 租户ID
     * @return 祖先角色列表
     */
    List<Role> selectAncestorRoles(@Param("roleId") String roleId);
    
    /**
     * 查询角色的所有后代角色（向下查询）
     * 
     * @param roleId 角色ID
     * @param tenantId 租户ID
     * @return 后代角色列表
     */
    List<Role> selectDescendantRoles(@Param("roleId") String roleId);
    
    // ==================== 数据权限查询 ====================
    
    /**
     * 查询用户的数据权限范围
     * 
     * 根据用户的角色配置，获取数据权限范围信息
     * 
     * @param userId 用户ID
     * @param tenantId 租户ID
     * @return 数据权限信息列表
     */
    List<com.kexio.auth.dto.DataScopeInfo> selectUserDataScope(@Param("userId") String userId);
    
    /**
     * 查询角色的数据权限部门范围
     * 
     * @param roleId 角色ID
     * @param tenantId 租户ID
     * @return 部门ID列表
     */
    List<String> selectRoleDataScopeDepts(@Param("roleId") String roleId);
    
    // ==================== 菜单关联查询 ====================
    
    /**
     * 查询角色关联的菜单列表
     * 
     * 通过角色权限关联和菜单权限关联查询角色可访问的菜单
     * 
     * @param roleId 角色ID
     * @param tenantId 租户ID
     * @return 菜单列表
     */
    List<com.kexio.user.entity.Menu> selectRoleMenus(@Param("roleId") String roleId);
    
    /**
     * 删除角色的所有菜单关联
     * 
     * @param roleId 角色ID
     * @param tenantId 租户ID
     * @return 删除的记录数
     */
    int deleteRoleMenusByRoleId(@Param("roleId") String roleId);
    
    /**
     * 批量插入角色菜单关联
     * 
     * @param roleMenus 角色菜单关联列表
     * @return 插入的记录数
     */
    int batchInsertRoleMenus(@Param("roleMenus") List<com.kexio.user.entity.RoleMenu> roleMenus);
    
    // ==================== 统计查询 ====================
    
    /**
     * ✅ 批量查询所有角色及其用户数量（一条SQL搞定）
     * 
     * @return 角色分布统计列表，每个元素包含 role_name 和 user_count
     */
    List<java.util.Map<String, Object>> selectRoleDistributionStats();
    
    /**
     * 统计租户角色总数
     * 
     * @param tenantId 租户ID
     * @return 角色总数
     */
    default long countRolesByTenant() {
        LambdaQueryWrapper<Role> wrapper = new LambdaQueryWrapper<>();
        return this.selectCount(wrapper);
    }
    
    /**
     * 统计启用的角色数量
     * 
     * @param tenantId 租户ID
     * @return 启用角色数
     */
    default long countActiveRoles() {
        LambdaQueryWrapper<Role> wrapper = new LambdaQueryWrapper<>();
        wrapper.eq(Role::getStatus, 1);
        return this.selectCount(wrapper);
    }
    
    // ==================== 状态查询 ====================
    
    /**
     * 查询启用状态的角色列表
     * 
     * @param tenantId 租户ID
     * @return 启用角色列表
     */
    List<Role> selectActiveRoles();
    
    /**
     * 查询指定状态的角色列表
     * 
     * @param status 角色状态
     * @param tenantId 租户ID
     * @return 角色列表
     */
    List<Role> selectRolesByStatus(@Param("status") String status);
}
